Unity Plugin接入指引
Plugin是专为Unity平台的移动终端(iOS/Android)游戏APP而开发的崩溃/异常捕获组件,它能够自动捕获C#脚本未处理的异常和原生代码(Objective-C、Java、C/C++等)未处理的异常,并提供实时、多维度的异常问题分析服务。
接入前准备
- 在接入sdk之前,请务必认真阅读《开发者合规指南》 。
- SDK在初始化过程中,可能会采集部分用户信息。请在用户同意《Bugly专业版SDK个人信息保护规则》之后,再进行SDK的初始化。SDK在初始化前,不会收集任何信息。
使用说明
- Bugly的内存和卡顿等性能监控存在一定的CPU消耗,请游戏业务在线上谨慎使用;
- 业务可以通过SDK配置中调整采样率控制某些能力使用;
插件下载
- 可以使用Unity插件将数据报到测试demo来验证数据
步骤一:注册产品,获取AppID及AppKey
请参考 快速入门,在Bugly专业版上创建新产品,创建成功后,在设置-->产品信息中,复制AppID及AppKey。
如果只是为了验证SDK,可以使用 Android体验demo 和 iOS体验demo的AppID以及AppKey。
步骤二:通用部分集成步骤
1.下载并导入Bugly Unity Plugin到Unity项目工程
- 下载最新版本BuglyPro Unity Plugin,双击.unitypackage文件,导入Plugin的相关文件到您的Unity工程中。双击buglypro_plugin_*.unitypackage文件,根据平台需求导入文件到Unity工程(如果你正在使用旧版本Plugin包,请务必先删除旧版本相关的文件)
>
> 下载包目录结构说明
>
> - buglyPro\_plugin_*.unitypackage - Bugly Unity Plugin包, 提供C#异常捕获功能及原生SDK接口封装
>bugly_plugin_*.unitypackage目录结构说明
- Assets/Plugins/BuglyPlugins - Plugin脚本
- Assets/Plugins/BuglyPlugins/Android/libs - Android平台依赖的原生SDK(.jar)及NDK组件(.so)
- Assets/BuglyPro.framework - iOS平台依赖的原生SDK静态库(默认使用libc++编译静态库, 如需使用libstdc++编译的静态库,可以使用BuglySDK/iOS/libstdc++/BuglyPro.framework替换)
注意:
- 集成Bugly Unity Plugin之后,还需集成对应的[iOS]或[Android]平台的SDK组件
- iOS的SDK组件可以在导出的Xcode工程中集成并修改配置(具体可以参考[iOS SDK接入指南][../ios]的工程配置章节),或者使用[XUPorter][https://github.com/onevcat/XUPorter.git]等插件自动集成,Unity 5.x将会自动集成工程目录的iOS静态库,但仍需在Xcode工程中修改必要的工程配置
- Android的SDK组件可以在导出的Android工程中集成并修改配置(具体可以参考[Android SDK接入指南][../android]),或直接把组件的内容拷贝到工程Plugins/Android目录下,并修改AndroidManifest.xml的权限声明
2. 初始化Bugly
- 选择第一个或主场景(Scene),在任意脚本文件(建议选择较早加载的脚本)中调用如下代码进行初始化。
// Config performance plugin to init
BuglyAgent.ConfigPluginArray(PluginArray);
#if UNITY_IPHONE || UNITY_IOS
BuglyAgent.InitWithAppId ("Your App ID", "Your App Key");
#elif UNITY_ANDROID
BuglyAgent.InitWithAppId ("Your App ID", "Your App Key");
#endif
// 如果你确认已在对应的iOS工程或Android工程中初始化SDK,那么在脚本中只需启动C#异常捕获上报功能即可
BuglyAgent.EnableExceptionHandler ();
3. iOS部分集成步骤
不发布到iOS平台可略过此部分
暂无
4. Android部分集成步骤
不发布到Android平台可略过此部分
修改Android工程的配置文件AndroidManifest.xml
此部分的配置你可以参考[Android SDK接入指南][7]
- 修改导出的Android工程的AndroidManifest.xml文件中的权限声明,添加如下权限:
<!-- 网络通信-->
<uses-permission android:name= "android.permission.INTERNET" />
<!-- 获取网络状态 -->
<uses-permission android:name="android.permission.ACCESS_NETWORK_STATE" />
<!-- 获取MAC地址-->
<uses-permission android:name="android.permission.ACCESS_WIFI_STATE" />
<!-- 获取设备信息 -->
<uses-permission android:name= "android.permission.READ_PHONE_STATE" />
<!-- 可选的权限: -->
<!-- 获取logcat日志 -->
<uses-permission android:name="android.permission.READ_LOGS" />注意:如果权限声明已经添加,不用重复添加
至此、Unity项目的Android工程配置完成。你可以在Unity项目中触发C#的异常进行测试验证。
API列表
BuglyAgent.InitWithAppId(string,string)
初始化Bugly,传入Bugly专业版网站注册获得的App ID和App Key。
启用native code(Obj-C、C/C++、Java)异常、C#异常捕获上报,如果你已经在相应的iOS或Android工程中初始化Bugly,那么你只需调用
BuglyAgent.EnableExceptionHandler
开启C#异常捕获上报即可。BuglyAgent.ConfigPluginArray(string[])
设置需要打开哪些监控模块,默认打开Android Crash、Android ANR、Android自定义错误、iOS Crash、iOS 自定义错误、iOS FOOM。
BuglyAgent.EnableExceptionHandler()
启动C#异常日志捕获上报,默认自动上报级别LogError,那么LogError、LogException的异常日志都会自动捕获上报。
日志级别定义参考LogSeverity : {LogDebug、LogWarning、LogAssert、LogError、LogException}
- BuglyAgent.RegisterLogCallback(BuglyAgent.LogCallbackDelegate)
注册LogCallbackDelegate回调方法, 处理系统的日志。
如果你的应用需要调用Application.RegisterLogCallback(LogCallback)等注册日志回调,你可以使用此方法进行替换。
BuglyAgent.ReportException (System.Exception, string)
上报已捕获C#异常,输入参数异常对象,附加描述信息
BuglyAgent.ReportException (string, string, string)
上报自定义错误信息,输入错误名称、错误原因、错误堆栈等信息
BuglyAgent.SetUserId (string)
设置用户标识,如果不设置,默认为Unknown。
在初始化之后调用
BuglyAgent.SetDeviceId (string)
设置设备标识,如果不设置,默认为Unknown。
在初始化之后调用
BuglyAgent.SetCrashAttachmentPaths (string [])
设置Crash自定义文件上报路径,最多支持10个路径。
在初始化之后调用
BuglyAgent.ConfigDefault (string, string, string, long)
修改应用默认配置信息:渠道号、版本、用户标识等。
在初始化之前调用
渠道号默认值为空,
版本默认值
- Android应用默认读取AndroidManifest.xml中的android:versionName
- iOS应用默认读取Info.plist文件中CFBundleShortVersionString和CFBundleVersion,拼接为CFBundleShortVersionString(CFBundleVersion)格式,例如1.0.1(10)
用户标识默认值10000
- BuglyAgent.ConfigAutoQuitApplication (bool)
配置是否在捕获上报C#异常信息后就立即退出应用,避免后续产生更多非预期的C#的异常。
在初始化之前调用
FAQ
- 为什么发生C#异常后,应用直接崩溃?
答: 如果遇到此场景,可以把脚本中
InitWithAppId
注释,保留EnableExceptionHandler
方法调用,并在对应的Android或iOS工程中初始化SDK的组件。